<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html
    PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<!-- ../src/examples/findfiles.qdoc -->
<head>
  <title>Find Files Example</title>
    <style type="text/css">h3.fn,span.fn { margin-left: 1cm; text-indent: -1cm; }
a:link { color: #004faf; text-decoration: none }
a:visited { color: #672967; text-decoration: none }
td.postheader { font-family: sans-serif }
tr.address { font-family: sans-serif }
body { color: black; }</style>
</head>
<body>
<h1 class="title">Find Files Example<br /><span class="subtitle"></span>
</h1>
<p>The Find Files example shows how to use QProgressDialog to provide feedback on the progress of a slow operation. The example also shows how to use QFileDialog to facilitate browsing, how to use QTextStream to read a file, and how to use QTableWidget to provide standard table display facilities for applications.</p>
<p align="center"><img src="classpath:com/trolltech/images/findfiles-example.png" alt="Screenshot of the Find Files example" /></p><p>With the Find Files application the user can search for files in a specified directory, matching a specified file name (using wild cards if appropiate) and containing a specified text.</p>
<p>The user is provided with a <b>Browse</b> option, and the result of the search is displayed in a table with the names of the files found and their sizes. In addition the application provides a total count of the files found.</p>
<a name="the-findfiles-class"></a>
<h2>The FindFiles Class</h2>
<p>The <tt>FindFiles</tt> class inherits QWidget, and is the main application widget. It shows the search options, and displays the search results. We first describe the API of the class and then review its methods. Data members are explained as we encounter them in the code.</p>
<p>We need two private slots: The <tt>browse()</tt> slot is called whenever the user wants to browse for a directory to search in, and the <tt>find()</tt> slot is called whenever the user requests a search to be performed by pressing the <b>Find</b> button.</p>
<p>In addition we declare several private methods: We use the <tt>findFiles()</tt> method to search for files matching the user's specifications, we call the <tt>showFiles()</tt> method to display the results, and we use <tt>createButton()</tt>, <tt>createComboBox()</tt> and <tt>createFilesTable()</tt> when we are constructing the widget.</p>
<p>In the constructor we first create the application's widgets.</p>
<pre>        public FindFiles()
        {
            browseButton = createButton(tr(&quot;&amp;Browse...&quot;), &quot;browse()&quot;);
            findButton = createButton(tr(&quot;&amp;Find&quot;), &quot;find()&quot;);

            fileComboBox = createComboBox(tr(&quot;*&quot;));
            textComboBox = createComboBox(&quot;&quot;);
            directoryComboBox = createComboBox(QDir.currentPath());

            fileLabel = new QLabel(tr(&quot;Named:&quot;));
            textLabel = new QLabel(tr(&quot;Containing text:&quot;));
            directoryLabel = new QLabel(tr(&quot;In directory:&quot;));
            filesFoundLabel = new QLabel();

            createFilesTable();</pre>
<p>We create the application's buttons using the private <tt>createButton()</tt> method. Then we create the comboboxes associated with the search specifications, using the private <tt>createComboBox()</tt> method. We also create the application's labels before we use the private <tt>createFilesTable()</tt> method to create the table displaying the search results.</p>
<pre>            QHBoxLayout buttonsLayout = new QHBoxLayout();
            buttonsLayout.addStretch();
            buttonsLayout.addWidget(findButton);

            QGridLayout mainLayout = new QGridLayout();
            mainLayout.addWidget(fileLabel, 0, 0);
            mainLayout.addWidget(fileComboBox, 0, 1, 1, 2);
            mainLayout.addWidget(textLabel, 1, 0);
            mainLayout.addWidget(textComboBox, 1, 1, 1, 2);
            mainLayout.addWidget(directoryLabel, 2, 0);
            mainLayout.addWidget(directoryComboBox, 2, 1);
            mainLayout.addWidget(browseButton, 2, 2);
            mainLayout.addWidget(filesTable, 3, 0, 1, 3);
            mainLayout.addWidget(filesFoundLabel, 4, 0);
            mainLayout.addLayout(buttonsLayout, 5, 0, 1, 3);
            setLayout(mainLayout);

            setWindowTitle(tr(&quot;Find Files&quot;));
            resize(700, 300);
        }</pre>
<p>Then we add all the widgets to a main layout using QGridLayout. We have, however, put the <tt>Find</tt> and <tt>Quit</tt> buttons and a stretchable space in a separate QHBoxLayout first, to make the buttons appear in the <tt>Window</tt> widget's bottom right corner.</p>
<pre>        private void browse()
        {
            String directory = QFileDialog.getExistingDirectory(this,
                                       tr(&quot;Find Files&quot;), QDir.currentPath());
            if (!directory.equals(&quot;&quot;)) {
                directoryComboBox.addItem(directory);
                directoryComboBox.setCurrentIndex(directoryComboBox.currentIndex() + 1);
            }
        }</pre>
<p>The <tt>browse()</tt> slot presents a file dialog to the user, using the QFileDialog class. QFileDialog enables a user to traverse the file system in order to select one or many files or a directory. The easiest way to create a QFileDialog is to use the convenience static methods.</p>
<p>Here we use the static QFileDialog::getExistingDirectory() method which returns an existing directory selected by the user. Then we display the directory in the directory combobox using the QComboBox::addItem() method, and updates the current index.</p>
<p>QComboBox::addItem() adds an item to the combobox with the given text, and containing the specified user data. The item is appended to the list of existing items. The current index holds the index of the current item in the combobox. So in order to display the item we just added, we need to update the index as well.</p>
<pre>        private void find()
        {
            filesTable.setRowCount(0);

            String fileName = fileComboBox.currentText();
            String text = textComboBox.currentText();
            String path = directoryComboBox.currentText();</pre>
<p>The <tt>find()</tt> slot is called whenever the user requests a new search by pressing the <b>Find</b> button.</p>
<p>First we eliminate any previous search results by setting the table widgets row count to zero. Then we retrieve the specified file name, text and directory path from the respective comboboxes.</p>
<pre>            QDir directory = new QDir(path);
            List&lt;String&gt; files = new LinkedList&lt;String&gt;();

            if (fileName.equals(&quot;&quot;))
                fileName = &quot;*&quot;;

            List&lt;String&gt; entries = new LinkedList&lt;String&gt;();
            entries.add(fileName);

            files = directory.entryList(entries,
                new QDir.Filters(QDir.Filter.Files, QDir.Filter.NoSymLinks));

            if (!text.equals(&quot;&quot;))
                files = findFiles(directory, files, text);
            showFiles(directory, files);
        }</pre>
<p>We use the directory's path to create a QDir; the QDir class provides access to directory structures and their contents. We create a list of the files (contained in the newly created QDir) that match the specified file name. If the file name is empty the list will contain all the files in the directory.</p>
<p>Then we search through all the files in the list, using the private <tt>findFiles()</tt> method, eliminating the ones that don't contain the specified text. And finally, we display the results using the private <tt>showFiles()</tt> method.</p>
<p>If the user didn't specify any text, there is no reason to search through the files, and we display the results immediately.</p>
<p align="center"><img src="classpath:com/trolltech/images/findfiles_progress_dialog.png" alt="Screenshot of the Progress Dialog" /></p><pre>        private List&lt;String&gt; findFiles(QDir directory, List&lt;String&gt; files,
                                       String text)
        {
            QProgressDialog progressDialog = new QProgressDialog(this);
            progressDialog.setCancelButtonText(tr(&quot;&amp;Cancel&quot;));
            progressDialog.setRange(0, files.size());
            progressDialog.setWindowTitle(tr(&quot;Find Files&quot;));</pre>
<p>In the private <tt>findFiles()</tt> method we search through a list of files, looking for the ones that contain a specified text. This can be a very slow operation depending on the number of files as well as their sizes. In case there are a large number of files, or there exists some large files on the list, we provide a QProgressDialog.</p>
<p>The QProgressDialog class provides feedback on the progress of a slow operation. It is used to give the user an indication of how long an operation is going to take, and to demonstrate that the application has not frozen. It can also give the user an opportunity to abort the operation.</p>
<pre>            List&lt;String&gt; foundFiles = new LinkedList&lt;String&gt;();

            for (int i = 0; i &lt; files.size(); ++i) {
                progressDialog.setValue(i);
                progressDialog.setLabelText(tr(&quot;Searching file number &quot;+i+
                                               &quot; of &quot;+files.size()+&quot;...&quot;));
                QApplication.processEvents();

                if (progressDialog.wasCanceled())
                    break;</pre>
<p>We run through the files, one at a time, and for each file we update the QProgressDialog value. This property holds the current amount of progress made. We also update the progress dialog's label.</p>
<p>Then we call the QCoreApplication::processEvents() method using the QApplication object. In this way we interleave the display of the progress made with the process of searching through the files so the application doesn't appear to be frozen.</p>
<p>The QApplication class manages the GUI application's control flow and main settings. It contains the main event loop, where all events from the window system and other sources are processed and dispatched. QApplication inherits QCoreApplication. The QCoreApplication::processEvents() method processes all pending events according to the specified QEventLoop::ProcessEventFlags until there are no more events to process. The default flags are QEventLoop::AllEvents.</p>
<pre>                QFile file = new QFile(directory.absoluteFilePath(files.get(i)));

                if (file.open(QIODevice.OpenModeFlag.ReadOnly)) {
                    String line = &quot;&quot;;
                    QTextStream in = new QTextStream(file);
                    while (!in.atEnd()) {
                        if (progressDialog.wasCanceled())
                            break;
                        line = in.readLine();
                        if (line.contains(text)) {
                            foundFiles.add(files.get(i));
                            break;
                        }
                    }
                }
            }
            return foundFiles;
        }</pre>
<p>After updating the QProgressDialog, we create a QFile using the QDir::absoluteFilePath() method which returns the absolute path name of a file in the directory. We open the file in read-only mode, and read one line at a time using QTextStream.</p>
<p>For each line we read we check if the QProgressDialog has been canceled. If it has, we abort the operation, otherwise we check if the line contains the specified text. When we find the text within one of the files, we add the file's name to a list of found files that contain the specified text, and start searching a new file.</p>
<p>Finally, we return the list of the files found.</p>
<pre>        private void showFiles(QDir directory, List&lt;String&gt; files)
        {
            for (int i = 0; i &lt; files.size(); ++i) {
                QFile file = new QFile(directory.absoluteFilePath(files.get(i)));
                long size = new QFileInfo(file).size();

                QTableWidgetItem fileNameItem = new QTableWidgetItem(files.get(i));
                fileNameItem.setFlags(Qt.ItemFlag.ItemIsEnabled);
                QTableWidgetItem sizeItem =
                    new QTableWidgetItem(&quot;&quot; + ((size + 1023) / 1024) + tr(&quot;KB&quot;));
                sizeItem.setTextAlignment(new Qt.Alignment(Qt.AlignmentFlag.AlignRight,
                                                           Qt.AlignmentFlag.AlignVCenter).value());
                sizeItem.setFlags(Qt.ItemFlag.ItemIsEnabled);

                int row = filesTable.rowCount();
                filesTable.insertRow(row);
                filesTable.setItem(row, 0, fileNameItem);
                filesTable.setItem(row, 1, sizeItem);
            }
            filesFoundLabel.setText(&quot;&quot; + files.size() + tr(&quot;file(s) found.&quot;));
        }</pre>
<p>Both the <tt>findFiles()</tt> and <tt>showFiles()</tt> methods are called from the <tt>find()</tt> slot. In the <tt>showFiles()</tt> method we run through the provided list of file names, adding each file name to the first column in the table widget and retrieving the file's size using QFile and QFileInfo for the second column.</p>
<p>We also update the total number of files found.</p>
<pre>        private QPushButton createButton(String text, String goldMember)
        {
            QPushButton button = new QPushButton(text);
            button.clicked.connect(this, goldMember);

            return button;
        }</pre>
<p>The private <tt>createButton()</tt> method is called from the constructor. We create a QPushButton with the provided text, connect it to the provided slot, and return a pointer to the button.</p>
<pre>        private QComboBox createComboBox(String text)
        {
            QComboBox comboBox = new QComboBox();
            comboBox.setEditable(true);
            comboBox.addItem(text);
            comboBox.setSizePolicy(QSizePolicy.Policy.Expanding,
                                   QSizePolicy.Policy.Preferred);

            return comboBox;
        }</pre>
<p>The private <tt>createComboBox()</tt> method is also called from the contructor. We create a QComboBox with the given text, and make it editable.</p>
<p>When the user enters a new string in an editable combobox, the widget may or may not insert it, and it can insert it in several locations, depending on the QComboBox::InsertPolicy. The default policy is is QComboBox::InsertAtBottom.</p>
<p>Then we add the provided text to the combobox, and specify the widget's size policies, before we return a pointer to the combobox.</p>
<pre>        private void createFilesTable()
        {
            filesTable = new QTableWidget(0, 2);

            List&lt;String&gt; labels = new LinkedList&lt;String&gt;();
            labels.add(tr(&quot;File Name&quot;));
            labels.add(tr(&quot;Size&quot;));

            filesTable.setHorizontalHeaderLabels(labels);
            filesTable.horizontalHeader().setResizeMode(0, QHeaderView.ResizeMode.Stretch);
            filesTable.verticalHeader().hide();
            filesTable.setShowGrid(false);
        }</pre>
<p>The private <tt>createFilesTable()</tt> method is called from the constructor. In this method we create the QTableWidget that will display the search results. We set its horizontal headers and their resize mode.</p>
<p>QTableWidget inherits QTableView which provides a default model/view implementation of a table view. The QTableView::horizontalHeader() method returns the table view's horizontal header as a QHeaderView. The QHeaderView class provides a header row or header column for item views, and the QHeaderView::setResizeMode() method sets the constraints on how the section in the header can be resized.</p>
<p>Finally, we hide the QTableWidget's vertical headers using the QWidget::hide() method, and remove the default grid drawn for the table using the QTableView::setShowGrid() method.</p>
</body>
</html>
